<div class="tmd-doc">
<h1 class="tmd-header-1">
Introduction to Source Code Elements
</h1>
<p></p>
<div class="tmd-usual">
Go is known for its simple and clean syntax. This article introduces the common source code elements in programming through a simple example. This will help new gophers (Go programmers) get a basic idea of the usage of Go elements.
</div>
<p></p>
<h3 class="tmd-header-3">
Programming and Source Code Elements
</h3>
<p></p>
<div class="tmd-usual">
Programming can be viewed as manipulating operations in all kinds of ways to reach certain goals. Operations write data to and read data from hardware devices to complete tasks. For modern computers, elemental operations are low-level CPU and GPU instructions. Common hardware devices include memory, disk, network card, graphics card, monitor, keyboard and mouse, etc.
</div>
<p></p>
<div class="tmd-usual">
Programming by manipulating low-level instructions directly is tedious and error-prone. High-level programming languages make some encapsulations for low-level operations, and make some abstracts for data, to make programming more intuitive and human-friendly.
</div>
<p></p>
<div class="tmd-usual">
In popular high-level programming languages, operations are mainly achieved by calling <span class="tmd-bold">functions</span> and using <span class="tmd-bold">operators</span>. Most popular high-level programming languages support several kinds of conditional and loop <span class="tmd-bold">control flows</span>, we can think of them as special operations. The syntax of these control flows is close to human language so that the code written by programmers is easy to understand.
</div>
<p></p>
<div class="tmd-usual">
Data is abstracted as <span class="tmd-bold">types</span> and <span class="tmd-bold">values</span> in most high-level programming languages. Types can be viewed as value templates, and values can be viewed as type instances. Most languages support several built-in types, and also support custom types. The type system of a programming language is the spirit of the language.
</div>
<p></p>
<div class="tmd-usual">
There may be a large number of values used in programming. Some of them can be represented with their <span class="tmd-bold">literals</span> (text representations) directly, but others can't. To make programming flexible and less error-prone, many values are named. Such values include <span class="tmd-bold">variables</span> and named <span class="tmd-bold">constants</span>.
</div>
<p></p>
<div class="tmd-usual">
Named functions, named values (including variables and named constants), defined types and type alias are called <span class="tmd-bold">code elements</span>. The names of code elements must be <span class="tmd-bold"></span><a href="keywords-and-identifiers.html#identifier"><span class="tmd-bold">identifiers</span></a><span class="tmd-bold"></span>. Package names and package import names shall also be identifiers.
</div>
<p></p>
<p></p>
<div class="tmd-usual">
High-level programming code will be translated to low-level CPU instructions by compilers to get executed. To help compilers parse high-level programming code, many words are reserved to prevent them from being used as identifiers. Such words are called <span class="tmd-bold"></span><a href="keywords-and-identifiers.html#keyword"><span class="tmd-bold">keywords</span></a><span class="tmd-bold"></span>.
</div>
<p></p>
<p></p>
<div class="tmd-usual">
Many modern high-level programming languages use <span class="tmd-bold">packages</span> to organize code. A package must <span class="tmd-bold">import</span> another package to use the exported (public) code elements in the other package. Package names and package import names shall also be identifiers.
</div>
<p></p>
<div class="tmd-usual">
Although the code written in high-level programming languages is more understandable than low-level machine languages, we still need some comments for some code to explain the logic. The example program in the next section contains many comments.
</div>
<p></p>
<h3 class="tmd-header-3">
A Simple Go Demo Program
</h3>
<p></p>
<div class="tmd-usual">
Let's view a short Go demo program to know all kinds of code elements in Go. Like some other languages, in Go, line comments start with <code class="tmd-code-span">//</code>, and each block comment is enclosed in a pair of <code class="tmd-code-span">/*</code> and <code class="tmd-code-span">*/</code>.
</div>
<p></p>
<div class="tmd-usual">
Below is the demo Go program. Please read the comments for explanations. More explanations are following the program.
</div>
<p></p>
<pre class="tmd-code line-numbers must-line-numbers">
<code class="language-go">package main // specify the source file's package

import "math/rand" // import a standard package

const MaxRnd = 16 // a named constant declaration

// A function declaration
/*
 StatRandomNumbers produces a certain number of
 non-negative random integers which are less than
 MaxRnd, then counts and returns the numbers of
 small and large ones among the produced randoms.
 n specifies how many randoms to be produced.
*/
func StatRandomNumbers(n int) (int, int) {
	// Declare two variables (both as 0).
	var a, b int
	// A for-loop control flow.
	for i := 0; i &lt; n; i++ {
		// An if-else control flow.
		if rand.Intn(MaxRnd) &lt; MaxRnd/2 {
			a = a + 1
		} else {
			b++ // same as: b = b + 1
		}
	}
	return a, b // this function return two results
}

// "main" function is the entry function of a program.
func main() {
	var num = 100
	// Call the declared StatRandomNumbers function.
	x, y := StatRandomNumbers(num)
	// Call two built-in functions (print and println).
	print("Result: ", x, " + ", y, " = ", num, "? ")
	println(x+y == num)
}
</code></pre>
<p></p>
<div class="tmd-usual">
Save above source code to a file named <code class="tmd-code-span">basic-code-element-demo.go</code> and run this program by:
</div>
<pre class="tmd-code output">
$ go run basic-code-element-demo.go
Result: 46 + 54 = 100? true
</pre>
<p></p>
<div class="tmd-usual">
In the above program, <code class="tmd-code-span">package</code>, <code class="tmd-code-span">import</code>, <code class="tmd-code-span">const</code>, <code class="tmd-code-span">func</code>, <code class="tmd-code-span">var</code>, <code class="tmd-code-span">for</code>, <code class="tmd-code-span">if</code>, <code class="tmd-code-span">else</code>, and <code class="tmd-code-span">return</code> are all keywords. Most other words in the program are identifiers. Please read <a href="keywords-and-identifiers.html">keywords and identifiers</a> for more information about keywords and identifiers.
</div>
<p></p>
<p></p>
<p></p>
<div class="tmd-usual">
The four <code class="tmd-code-span">int</code> words at line <span class="tmd-italic">15</span> and line <span class="tmd-italic">17</span> denote the built-in <code class="tmd-code-span">int</code> type, one of many kinds of integer types in Go. The <code class="tmd-code-span">16</code> at line <span class="tmd-italic">5</span>, <code class="tmd-code-span">0</code> at line <span class="tmd-italic">19</span>, <code class="tmd-code-span">2</code> at line <span class="tmd-italic">21</span>, <code class="tmd-code-span">1</code> at line <span class="tmd-italic">22</span> and <code class="tmd-code-span">100</code> at line <span class="tmd-italic">32</span> are some integer literals. The <code class="tmd-code-span">"Result: "</code> at line <span class="tmd-italic">36</span> is a string literal. Please read <a href="basic-types-and-value-literals.html">basic types and their value literals</a> for more information about above built-in basic types and their value literals. Some other types (composite types) will be introduced later in other articles.
</div>
<p></p>
<p></p>
<div class="tmd-usual">
Line <span class="tmd-italic">22</span> is an assignment. Line <span class="tmd-italic">5</span> declares a named constant, <code class="tmd-code-span">MaxRnd</code>. Line <span class="tmd-italic">17</span> and line <span class="tmd-italic">32</span> declare three variables, with the standard variable declaration form. Variables <code class="tmd-code-span">i</code> at line <span class="tmd-italic">19</span>, <code class="tmd-code-span">x</code> and <code class="tmd-code-span">y</code> at line <span class="tmd-italic">34</span> are declared with the short variable declaration form. We have specified the type for variables <code class="tmd-code-span">a</code> and <code class="tmd-code-span">b</code> as <code class="tmd-code-span">int</code>. Go compiler will deduce that the types of <code class="tmd-code-span">i</code>, <code class="tmd-code-span">num</code>, <code class="tmd-code-span">x</code> and <code class="tmd-code-span">y</code> are all <code class="tmd-code-span">int</code>, because they are initialized with integer literals. Please read <a href="constants-and-variables.html">constants and variables</a> for more information about untyped values, type deduction, value assignments, and how to declare variables and named constants.
</div>
<p></p>
<p></p>
<div class="tmd-usual">
There are many operators used in the program, such as the less-than comparison operator <code class="tmd-code-span">&lt;</code> at line <span class="tmd-italic">19</span> and <span class="tmd-italic">21</span>, the equal-to operator <code class="tmd-code-span">==</code> at line <span class="tmd-italic">37</span>, and the addition operator <code class="tmd-code-span">+</code> at line <span class="tmd-italic">22</span> and line <span class="tmd-italic">37</span>. Yes, <code class="tmd-code-span">+</code> at line <span class="tmd-italic">36</span> is not an operator, it is one character in a string literal. The values involved in an operator operation are called operands. Please read <a href="operators.html">common operators</a> for more information. More operators will be introduced in other articles later.
</div>
<p></p>
<p></p>
<div class="tmd-usual">
At line <span class="tmd-italic">36</span> and line <span class="tmd-italic">37</span>, two built-in functions, <code class="tmd-code-span">print</code> and <code class="tmd-code-span">println</code>, are called. A custom function <code class="tmd-code-span">StatRandomNumbers</code> is declared from line <span class="tmd-italic">15</span> to line <span class="tmd-italic">28</span>, and is called at line <span class="tmd-italic">34</span>. Line <span class="tmd-italic">21</span> also calls a function, <code class="tmd-code-span">Intn</code>, which is a function declared in the <code class="tmd-code-span">math/rand</code> standard package. A function call is a function operation. The input values used in a function call are called arguments. Please read <a href="function-declarations-and-calls.html">function declarations and calls</a> for more information.
</div>
<p></p>
<p></p>
<div class="tmd-usual">
<span class="tmd-italic">(Note, the built-in <code class="tmd-code-span">print</code> and <code class="tmd-code-span">println</code> functions are not recommended to be used in formal Go programming. The corresponding functions in the <code class="tmd-code-span">fmt</code> standard packages should be used instead in formal Go projects. In Go 101, the two functions are only used in the several starting articles.)</span>
</div>
<p></p>
<div class="tmd-usual">
Line <span class="tmd-italic">1</span> specifies the package name of the current source file. The <code class="tmd-code-span">main</code> entry function must be declared in a package which is also called <code class="tmd-code-span">main</code>. Line <span class="tmd-italic">3</span> imports a package, the <code class="tmd-code-span">math/rand</code> standard code package. Its import name is <code class="tmd-code-span">rand</code>. The function <code class="tmd-code-span">Intn</code> declared in this standard package is called at line <span class="tmd-italic">21</span>. Please read <a href="packages-and-imports.html">code packages and package imports</a> for more information about how to organize code packages and import packages.
</div>
<p></p>
<p></p>
<div class="tmd-usual">
The article <a href="expressions-and-statements.html">expressions, statements and simple statements</a> will introduce what are expressions and statements. In particular, all kinds of simple statements, which are special statements, are listed. Some portions of all kinds of control flows must be simple statements, and some portions must be expressions.
</div>
<p></p>
<p></p>
<div class="tmd-usual">
In the <code class="tmd-code-span">StatRandomNumbers</code> function body, two control flows are used. One is a <code class="tmd-code-span">for</code> loop control flow, which nests the other one, an <code class="tmd-code-span">if-else</code> conditional control flow. Please read <a href="control-flows.html">basic control flows</a> for more information about all kinds of basic control flows. Some other special control flows will be introduced in other articles later.
</div>
<p></p>
<p></p>
<div class="tmd-usual">
Blank lines have been used in the above program to improve the readability of the code. And as this program is for code elements introduction purpose, there are many comments in it. Except the documentation comment for the <code class="tmd-code-span">StatRandomNumbers</code> function, other comments are for demonstration purpose only. We should try to make code self-explanatory and only use necessary comments in formal projects.
</div>
<p></p>
<h3 id="line-break" class="tmd-header-3">
About Line Breaks
</h3>
<p></p>
<div class="tmd-usual">
Like many other languages, Go also uses a pair of braces (<code class="tmd-code-span">{</code> and <code class="tmd-code-span">}</code>) to form an explicit code block. However, in Go programming, coding style can't be arbitrary. For example, many of the starting curly braces (<code class="tmd-code-span">{</code>) can't be put on the next line. If we modify the <code class="tmd-code-span">StatRandomNumbers</code> function declaration in the above program as the following, the program will fail to compile.
</div>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">func StatRandomNumbers(n int) (int, int)
{ // syntax error
	var a, b int
	for i := 0; i &lt; n; i++
	{ // syntax error
		if rand.Intn(MaxRnd) &lt; MaxRnd/2
		{ // syntax error
			a = a + 1
		} else {
			b++
		}
	}
	return a, b
}
</code></pre>
<div class="tmd-usual">
Some programmers may not like the line break restrictions. But the restrictions have two benefits:
</div>
<ol class="tmd-list">
<li class="tmd-list-item">
<div class="tmd-usual">
they make code compilations become faster.
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
they make the coding styles written by different gophers look similar, so that it is more easily for gophers to read and understand the code written by other gophers.
</div>
</li>
</ol>
<p></p>
<div class="tmd-usual">
We can learn more about line break rules in <a href="line-break-rules.html">a later article</a>. At present, we should avoid putting a starting curly brace on a new line. In other words, generally, the first non-blank character of a code line should not be the starting curly brace character. (But, please remember, this is not a universal rule.)
</div>
<p></p>
<p></p>
</div>
